/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.configuration.event;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.Iterator;
import java.util.LinkedList;
/**
* <p>
* A base class for objects that can generate configuration events.
* </p>
* <p>
* This class implements functionality for managing a set of event listeners
* that can be notified when an event occurs. It can be extended by
* configuration classes that support the event machanism. In this case these
* classes only need to call the <code>fireEvent()</code> method when an event
* is to be delivered to the registered listeners.
* </p>
* <p>
* Adding and removing event listeners can happen concurrently to manipulations
* on a configuration that cause events. The operations are synchronized.
* </p>
* <p>
* With the <code>detailEvents</code> property the number of detail events can
* be controlled. Some methods in configuration classes are implemented in a way
* that they call other methods that can generate their own events. One example
* is the <code>setProperty()</code> method that can be implemented as a
* combination of <code>clearProperty()</code> and <code>addProperty()</code>.
* With <code>detailEvents</code> set to <b>true</b>, all involved methods
* will generate events (i.e. listeners will receive property set events,
* property clear events, and property add events). If this mode is turned off
* (which is the default), detail events are suppressed, so only property set
* events will be received. Note that the number of received detail events may
* differ for different configuration implementations.
* <code>{@link org.apache.commons.configuration.HierarchicalConfiguration HierarchicalConfiguration}</code>
* for instance has a custom implementation of <code>setProperty()</code>,
* which does not generate any detail events.
* </p>
* <p>
* In addition to "normal" events, error events are supported. Such
* events signal an internal problem that occurred during access of properties.
* For them a special listener interface exists:
* <code>{@link ConfigurationErrorListener}</code>. There is another set of
* methods dealing with event listeners of this type. The
* <code>fireError()</code> method can be used by derived classes to send
* notifications about errors to registered observers.
* </p>
*
* @author <a href="http://commons.apache.org/configuration/team-list.html">Commons Configuration team</a>
* @version $Id: EventSource.java 561230 2007-07-31 04:17:09Z rahul $
* @since 1.3
*/
public class EventSource
{
/** A collection for the registered event listeners. */
private Collection listeners;
/** A collection for the registered error listeners.*/
private Collection errorListeners;
/** A counter for the detail events. */
private int detailEvents;
/**
* Creates a new instance of <code>EventSource</code>.
*/
public EventSource()
{
initListeners();
}
/**
* Adds a configuration listener to this object.
*
* @param l the listener to add
*/
public void addConfigurationListener(ConfigurationListener l)
{
doAddListener(listeners, l);
}
/**
* Removes the specified event listener so that it does not receive any
* further events caused by this object.
*
* @param l the listener to be removed
* @return a flag whether the event listener was found
*/
public boolean removeConfigurationListener(ConfigurationListener l)
{
return doRemoveListener(listeners, l);
}
/**
* Returns a collection with all configuration event listeners that are
* currently registered at this object.
*
* @return a collection with the registered
* <code>ConfigurationListener</code>s (this collection is a snapshot
* of the currently registered listeners; manipulating it has no effect
* on this event source object)
*/
public Collection getConfigurationListeners()
{
return doGetListeners(listeners);
}
/**
* Removes all registered configuration listeners.
*/
public void clearConfigurationListeners()
{
doClearListeners(listeners);
}
/**
* Returns a flag whether detail events are enabled.
*
* @return a flag if detail events are generated
*/
public boolean isDetailEvents()
{
synchronized (listeners)
{
return detailEvents > 0;
}
}
/**
* Determines whether detail events should be generated. If enabled, some
* methods can generate multiple update events. Note that this method
* records the number of calls, i.e. if for instance
* <code>setDetailEvents(false)</code> was called three times, you will
* have to invoke the method as often to enable the details.
*
* @param enable a flag if detail events should be enabled or disabled
*/
public void setDetailEvents(boolean enable)
{
synchronized (listeners)
{
if (enable)
{
detailEvents++;
}
else
{
detailEvents--;
}
}
}
/**
* Adds a new configuration error listener to this object. This listener
* will then be notified about internal problems.
*
* @param l the listener to register (must not be <b>null</b>)
* @since 1.4
*/
public void addErrorListener(ConfigurationErrorListener l)
{
doAddListener(errorListeners, l);
}
/**
* Removes the specified error listener so that it does not receive any
* further events caused by this object.
*
* @param l the listener to remove
* @return a flag whether the listener could be found and removed
* @since 1.4
*/
public boolean removeErrorListener(ConfigurationErrorListener l)
{
return doRemoveListener(errorListeners, l);
}
/**
* Removes all registered error listeners.
*
* @since 1.4
*/
public void clearErrorListeners()
{
doClearListeners(errorListeners);
}
/**
* Returns a collection with all configuration error listeners that are
* currently registered at this object.
*
* @return a collection with the registered
* <code>ConfigurationErrorListener</code>s (this collection is a
* snapshot of the currently registered listeners; it cannot be manipulated)
* @since 1.4
*/
public Collection getErrorListeners()
{
return doGetListeners(errorListeners);
}
/**
* Creates an event object and delivers it to all registered event
* listeners. The method will check first if sending an event is allowed
* (making use of the <code>detailEvents</code> property), and if
* listeners are registered.
*
* @param type the event's type
* @param propName the name of the affected property (can be <b>null</b>)
* @param propValue the value of the affected property (can be <b>null</b>)
* @param before the before update flag
*/
protected void fireEvent(int type, String propName, Object propValue, boolean before)
{
Collection listenersToCall = null;
synchronized (listeners)
{
if (detailEvents >= 0 && listeners.size() > 0)
{
// Copy listeners to another collection so that manipulating
// the listener list during event delivery won't cause problems
listenersToCall = new ArrayList(listeners);
}
}
if (listenersToCall != null)
{
ConfigurationEvent event = createEvent(type, propName, propValue, before);
for (Iterator it = listenersToCall.iterator(); it.hasNext();)
{
((ConfigurationListener) it.next()).configurationChanged(event);
}
}
}
/**
* Creates a <code>ConfigurationEvent</code> object based on the passed in
* parameters. This is called by <code>fireEvent()</code> if it decides
* that an event needs to be generated.
*
* @param type the event's type
* @param propName the name of the affected property (can be <b>null</b>)
* @param propValue the value of the affected property (can be <b>null</b>)
* @param before the before update flag
* @return the newly created event object
*/
protected ConfigurationEvent createEvent(int type, String propName, Object propValue, boolean before)
{
return new ConfigurationEvent(this, type, propName, propValue, before);
}
/**
* Creates an error event object and delivers it to all registered error
* listeners.
*
* @param type the event's type
* @param propName the name of the affected property (can be <b>null</b>)
* @param propValue the value of the affected property (can be <b>null</b>)
* @param ex the <code>Throwable</code> object that caused this error event
* @since 1.4
*/
protected void fireError(int type, String propName, Object propValue, Throwable ex)
{
Collection listenersToCall = null;
synchronized (errorListeners)
{
if (errorListeners.size() > 0)
{
// Copy listeners to another collection so that manipulating
// the listener list during event delivery won't cause problems
listenersToCall = new ArrayList(errorListeners);
}
}
if (listenersToCall != null)
{
ConfigurationErrorEvent event = createErrorEvent(type, propName, propValue, ex);
for (Iterator it = listenersToCall.iterator(); it.hasNext();)
{
((ConfigurationErrorListener) it.next()).configurationError(event);
}
}
}
/**
* Creates a <code>ConfigurationErrorEvent</code> object based on the
* passed in parameters. This is called by <code>fireError()</code> if it
* decides that an event needs to be generated.
*
* @param type the event's type
* @param propName the name of the affected property (can be <b>null</b>)
* @param propValue the value of the affected property (can be <b>null</b>)
* @param ex the <code>Throwable</code> object that caused this error
* event
* @return the event object
* @since 1.4
*/
protected ConfigurationErrorEvent createErrorEvent(int type, String propName, Object propValue, Throwable ex)
{
return new ConfigurationErrorEvent(this, type, propName, propValue, ex);
}
/**
* Overrides the <code>clone()</code> method to correctly handle so far
* registered event listeners. This implementation ensures that the clone
* will have empty event listener lists, i.e. the listeners registered at an
* <code>EventSource</code> object will not be copied.
*
* @return the cloned object
* @throws CloneNotSupportedException if cloning is not allowed
* @since 1.4
*/
protected Object clone() throws CloneNotSupportedException
{
EventSource copy = (EventSource) super.clone();
copy.initListeners();
return copy;
}
/**
* Adds a new listener object to a listener collection. This is done in a
* synchronized block. The listener must not be <b>null</b>.
*
* @param listeners the collection with the listeners
* @param l the listener object
*/
private static void doAddListener(Collection listeners, Object l)
{
if (l == null)
{
throw new IllegalArgumentException("Listener must not be null!");
}
synchronized (listeners)
{
listeners.add(l);
}
}
/**
* Removes an event listener from a listener collection. This is done in a
* synchronized block.
*
* @param listeners the collection with the listeners
* @param l the listener object
* @return a flag whether the listener could be found and removed
*/
private static boolean doRemoveListener(Collection listeners, Object l)
{
synchronized (listeners)
{
return listeners.remove(l);
}
}
/**
* Removes all entries from the given list of event listeners.
*
* @param listeners the collection with the listeners
*/
private static void doClearListeners(Collection listeners)
{
synchronized (listeners)
{
listeners.clear();
}
}
/**
* Returns an unmodifiable snapshot of the given event listener collection.
*
* @param listeners the collection with the listeners
* @return a snapshot of the listeners collection
*/
private static Collection doGetListeners(Collection listeners)
{
synchronized (listeners)
{
return Collections.unmodifiableCollection(new ArrayList(listeners));
}
}
/**
* Initializes the collections for storing registered event listeners.
*/
private void initListeners()
{
listeners = new LinkedList();
errorListeners = new LinkedList();
}
}